---
slug: "api/tags"
title: "Tags"
---

**Tags** are a special part of content piece metadata that can be used for labelling, organization and content filtering. The API provides you full control to retrieve and manage tags.

## Retrieve Tag

Retrieves details of the tag specified by ID.

<EndpointCard method="GET" endpoint="/tags">
  <ResponseExample>
    ```json
    {
      "id": "e99b9c3fadd9d6bcfc066627",
      "label": "string",
      "color": "gray"
    }
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    const result = await client.tags.get({
      id: "e99b9c3fadd9d6bcfc066627"
    });
    ```
  </RequestExample>
</EndpointCard>

## List Tags

Lists existing tags. Supports pagination.

<EndpointCard method="GET" endpoint="/tags/list">
  <ResponseExample>
    ```json
    [
      {
        "id": "f78094391d99f69e2a617086",
        "label": "string",
        "color": "gray"
      }
    ]
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>"
    });
    const result = await client.tags.list({
      // Optional
      page: 1,
      // Optional
      perPage: 20,
    });
    ```
  </RequestExample>
</EndpointCard>

## Create Tag

Creates a tag with specified label and color.

<EndpointCard method="POST" endpoint="/tags">
  <ResponseExample>
    ```json
    {
      "id": "2a8ace5b5814e98d68f6b607"
    }
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    const result = await client.tags.create({
      label: "string",
      // Optional
      color: "orange",
    });
    ```
  </RequestExample>
</EndpointCard>

## Update Tag

Updates the color or label of the tag matched by ID.

<EndpointCard method="PUT" endpoint="/tags">
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    await client.tags.update({
      id: "89b03aff4112d83c5c080daa",
      // Optional
      label: "string",
      // Optional
      color: "gray",
    });
    ```
  </RequestExample>
</EndpointCard>

## Delete Tag

Deletes the tag specified by ID, removing it from all content pieces and variants that it was assigned to.

<EndpointCard method="DELETE" endpoint="/tags">
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    await client.tags.delete({
      id: "89b03aff4112d83c5c080daa",
    });
    ```
  </RequestExample>
</EndpointCard>